Responds to cursor movements in a control while the mouse button is down and returns the location of the next mouse-up event.

ControlPartCode HandleControlClick (
    ControlRef inControl, 
    Point inWhere, 
    EventModifiers inModifiers, 
    ControlActionUPP inAction
);

inControl

A handle to the control in which the mouse-down event occurred. Pass the control handle returned by FindControl or FindControlUnderMouse.

inWhere

A point, specified in local coordinates, where the mouse-down event occurred. Supply the same point you passed to FindControl or FindControlUnderMouse.

inModifiers

Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted.

inAction

A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. See ControlActionProcPtr for a description of such an action function. The value of the inAction parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL). For custom controls, what you pass in this parameter depends on how you define the control. If the part index is greater than 128, the pointer must be of type DragGrayRegionUPP unless the control supports live feedback, in which case it should be a ControlActionUPP.

function result

Returns a value of type ControlPartCode identifying the control’s part; see “Meta Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”.

DISCUSSION

Call the HandleControlClick function after a call to FindControl or FindControlUnderMouse. The HandleControlClick function should be called instead of TrackControl to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike TrackControl, HandleControlClick allows modifier keys to be passed in so that the control may use these if the control (such as a list box or editable text field) is set up to handle its own tracking.

The visual feedback given by HandleControlClick depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, HandleControlClick highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, HandleControlClick responds by dragging a dotted outline or a ghost image of the indicator. If the user releases the mouse button when the cursor is in an indicator such as the scroll box, HandleControlClick calls the control definition function to reposition the indicator.

While the user holds down the mouse button with the cursor in one of the standard controls, HandleControlClick performs the following actions, depending on the value you pass in the parameter inAction.

• If you pass NULL in the inAction parameter, HandleControlClick uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for push buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
• If you pass a pointer to an action function in the inAction parameter, it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar.
• If you pass (ControlActionUPP)-1L in the inAction parameter, HandleControlClick looks in the contrlAction field of the control structure for a pointer to the control’s action function. This is appropriate when you are tracking the cursor in a pop-up menu. You can call GetControlAction to obtain the value of this field, and you can call SetControlAction to change this value. If the contrlAction field of the control structure contains a function pointer, HandleControlClick uses the action function it points to; if the field of the control structure also contains the value (ControlActionUPP)-1L, HandleControlClick calls the control definition function to perform the necessary action; you may wish to do this if you define your own control definition function for a custom control. If the field of the control structure contains the value NULL, HandleControlClick performs no action.

For 'CDEF' resources that implement custom dragging, you usually call HandleControlClick, which returns 0 regardless of the user’s changes of the control setting. To avoid this, you should use another method to determine whether the user has changed the control setting, for instance, comparing the control’s value before and after your call to HandleControlClick.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)